QuickTime 3 Reference
| Previous | Chapter Contents | Chapter Top | Next |
Use the QTCreateStandardParameterDialog function to display the standard parameters dialog box. This allows the user to choose an effect, adjust the settings for that effect, and see a preview of the effect with the selected settings.
Your application can use this function either to display a stand-alone dialog box, or to add the user interface elements from the standard parameter dialog box to one of the application's own dialog boxes. These options are discussed separately in the following sections.
For full details of the QTCreateStandardParameterDialog function, see the reference section "QTCreateStandardParameterDialog" .
When you call QTCreateStandardParameterDialog , QuickTime creates a standard parameters dialog box. The contents of the dialog box will vary, depending on the list of effects you passed to the function and the set of parameters that the currently chosen effect has.
Calling QTCreateStandardParameterDialog does not immediately display the dialog box, it only prepares it for display. The dialog box is shown the first time you call QTIsStandardParameterDialogEvent to process events for the dialog box. Event handling is described in "Processing Standard Parameter Dialog Box Events" .
The standard parameters dialog box for Apple's film noise effect is shown in Figure 9 .
Figure 9 The standard parameters dialog box showing Apple's Film Noise effect
Notice that the dialog box has three main sections. In the upper left corner is a scrolling list of all the components. To the right of this are displayed the parameters of the chosen effect. As you select different items in the list of effects, the parameters change appropriately. Finally, there is the effect preview, which is below the list of effects. This shows a preview of the currently chosen effect and parameter settings applied to a short preview movie clip.
The user interface for setting the value of the parameter may be a slider, as shown in the example above, a set of radio buttons, an editable text field, or any of several other interfaces specified in the parameter description's kParameterDataBehavior field.
The user is presented with a starting and ending value for parameters that are always tweens. For parameters that can be tweened optionally, the dialog box will present the user with a single value by default. In order to set such a parameter to a tweened value, the user must hold down the option key when selecting the effect the parameter belongs to.
The function call to create and display this dialog box is:
QTCreateStandardParameterDialog(theEffectList,
theEffectParameters,
0,
&createdDialogID);
The variable theEffectList holds list of effects that was returned by QTGetEffectsList . You can also pass nil for this value, in which case QTCreateStandardParameterDialog calls QTGetEffectsList to generate the list of all the currently installed effects, then shows these effects. The argument theEffectParameters contains a QTAtomContainer that holds the initial values of the effect's parameters. In most cases, you should pass an empty QTAtomContainer as this argument, in which case the default values of each effect are shown. When the user selects the dialog box's OK button, the chosen effect's parameter values are returned in theEffectParameters .
The parameter values are returned in a QT Atom container that you can use as an effect description. You will need to add kEffectSourceName atoms for effects that use one or more sources.
The third argument contains dialog options. See the reference section "QTCreateStandardParameterDialog" for details of the possible options values that can be passed.
The createdDialog argument returns an ID number that is passed to the other functions that deal with the standard parameters dialog box. This is explained in detail in the next section.
Once the dialog box has been created, you must process events sent to it using an event loop. You repeatedly call WaitNextEvent and pass the events returned through the QTIsStandardParameterDialogEvent function.
The QTIsStandardParameterDialogEvent function checks each event to see if it relates to the standard parameters dialog box. You should continue to handle events that are not related to the standard parameters dialog box as usual.
You should not use the ModalDialog function to process events for a standard parameters dialog box. The ModalDialog function is not guaranteed to work correctly in all circumstances with a standard parameters dialog box.
You pass the event record returned from WaitNextEvent to the function QTIsStandardParameterDialogEvent , then check the return value to find out how the events was handled. The possible return values are:
The QTIsStandardParameterDialogEvent function may also return error codes, as described in "QuickTime Video Effects Reference" . Your application should only process the event returned from WaitNextEvent if QTIsStandardParameterDialogEvent returns featureUnsupported .
The code in Listing 10 is an example event loop showing how QTIsStandardParameterDialogEvent is used.
Listing 10 An example event loop showing use of QTIsStandardParameterDialogEvent
while (result == noErr)
{
EventRecord theEvent;
WaitNextEvent(everyEvent, &theEvent, 0, nil);
result = QTIsStandardParameterDialogEvent(&theEvent,
createdDialogID);
switch (result)
{
case featureUnsupported:
{
result = noErr;
switch (theEvent.what)
{
case updateEvt:
BeginUpdate((WindowPtr) theEvent.message);
EndUpdate((WindowPtr) theEvent.message);
break;
}
break;
}
case codecParameterDialogConfirm:
case userCanceledErr:
QTDismissStandardParameterDialog(createdDialogID);
createdDialogID = nil;
break;
}
}
}
| Previous | Chapter Contents | Chapter Top | Next |